Elasticsearch QueryString Query Syntax Notes

TLDR

• query_string is a Lucene-based query syntax, suitable for quick retrieval.
• The default operator is OR. When searching for multiple terms in a keyword type field, you must wrap them in double quotes or use OR to connect them.
• Comparison operators (e.g., >, <) are not supported when using the fields array parameter; it is recommended to use the range query syntax [x TO y] instead.
• Date queries do not support comparison operators, and standard formats (containing :) must be wrapped in double quotes.
• Fuzzy search ~ and proximity search ~N must be used in conjunction with fuzziness or phrase_slop parameters, and settings within the query string take precedence over API parameters.
• Field boosting ^ affects the relative score between fields, while query boost affects the relative importance of clauses in a compound query.

---

Basic Syntax and API Structure

query_string is an extension of the Lucene query syntax in Elasticsearch, suitable for quick full-text search in interfaces like Elasticvue or Kibana Discover.

Basic API Structure

{
  "query": {
    "query_string": {
      "query": "your query string here",
      "default_field": "content",
      "default_operator": "OR"
    }
  },
  "size": 10,
  "from": 0,
  "sort": []
}

---

Differences in Query Syntax Behavior

Search Behavior by Field Type

When do you encounter issues where data cannot be found? When performing multi-term searches on keyword or numeric fields, if double quotes or operators are not used correctly, the search will fail because the terms cannot be tokenized.

Field Type	Query String	Behavior Description
text	apple banana	Equivalent to apple OR banana; matches if any term is found
keyword	"apple" "banana"	Must explicitly search for multiple complete strings using double quotes, or use OR
Numeric/Date	123 456	No results, because query_string does not automatically split multiple complete values

---

Range Queries and Comparison Operators

Comparison Operator Limitations

When do you encounter query errors? Using the fields array parameter in query_string combined with comparison operators (like >, >=) will cause parsing to fail.

• Recommended Approach: Use the range query syntax [x TO y] instead, as this syntax is fully compatible with the fields parameter.

// ❌ Incorrect: Using the fields array will cause the query to fail
{
  "query": {
    "query_string": {
      "query": ">=10",
      "fields": ["price"]
    }
  }
}

// ✅ Correct: Using range query syntax
{
  "query": {
    "query_string": {
      "query": "[10 TO *]",
      "fields": ["price"]
    }
  }
}

---

Date and Time Queries

Date Query Considerations

When do you encounter failures in date queries? When using comparison operators to query dates, or when a date format contains a colon (:) but is not wrapped in double quotes.

• Standard formats require double quotes: Because : is a special character, e.g., timestamp:"2023-01-15T08:30:00Z".
• Comparison operators are not supported: Date fields do not support > or <; please use the [start TO end] range syntax.
• Format strictness: If a specific format is defined for the field, the query string must strictly match that format, otherwise a failed to parse date field error will occur.

---

Weight Control: Boost and Field Boosting

Field Boost

Use the ^ syntax to adjust the weight of specific fields. This is suitable for scenarios where you want to emphasize that the Title is more representative than the Content during multi-field searches.

{
  "query_string": {
    "query": "apple iphone",
    "fields": ["title^3", "content"]
  }
}

Query Boost

In a bool compound query, adjust the importance of the entire query clause. Note: If used in a standalone query, boost will not change the sorting results.

---

Fuzzy Search and Proximity Search

Fuzzy and Proximity Syntax

When do you encounter ineffective parameter settings? When the ~ symbol is not included in the query string, global fuzziness or phrase_slop parameters will not take effect.

• Fuzzy search (~): Used after a single word to handle spelling errors.
• Proximity search (~N): Used after a phrase enclosed in quotes to handle word order and distance (Slop).

Precedence Rules:

1. ~N (explicit number) in the query string has the highest priority.
2. ~ (without a number) in the query string works in conjunction with API parameters.
3. If ~ is absent, it is treated as an exact match, and parameter settings are ineffective.

---

Changelog

1. 2025-04-13

   • Initial documentation created.
2. 2025-10-03

   • Refined phrasing and standardized terminology for Taiwan usage.
   • Corrected the explanation of date query range syntax (date fields do not support comparison operators; range query syntax should be used).
   • Corrected the section on weight calculation regarding missing field base scores.
   • Added technical details.